Docker와 Spring boot 설정하기(Window 환경)

✒️ 2025-07-28 14:44 내용 수정

Docker 사용을 위한 Window 가상 서버 설정를 먼저 진행해야 한다.

참고 자료 : Spring Boot with Docker

1. Spring Project 설정

• 프로젝트는 아래 구조처럼 작성했다.
  • 테스트를 위한 Controller 클래스만 설정했다.
  • resources에 application.yml 파일은 간단한 설정만 적용했다.
  • Dockerfile과 .dockerignore 파일은 프로젝트의 root 경로 바로 아래에 생성한다.

docker/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   ├── com.example.docker
│   │   │      ├── controller/
│   │   │      │   └── HelloController.java
│   │   │      └── DockerApplication.java
│   │   ├── resources/
│   │       ├── static/
│   │       ├── templates/
│   │       ├── application.properties
│   │       └── application.yml
├── Dockerfile
├── .dockerignore
├── mvnw
├── mvnw.cmd
└── pom.xml

Controller 설정

@RestController  
@RequestMapping("/api")  
public class HelloController {  
	@GetMapping  
	public String home() {  
		return "Docker Test";  
	}  
}

application.yml 설정

spring:  
	application:  
		name: spring-docker-demo  
  
server:  
	port: 8080  
  
app:  
	version: ${APP_VERSION:1.0.0}

.dockerignore 설정

# Docker 빌드에서 제외할 파일/폴더 추가
target/  
!target/*.jar  
*.log  
.git  
.idea  
*.iml

Dockerfile 설정

• FROM으로 컨테이너의 기본 베이스 이미지를 선택한다.
• WORKDIR로 명령문을 실행할 때의 기본 작업 디렉터리를 생성한다.
• COPY로 로컬 파일을 컨테이너 내부로 복사한다.
• ENTRYPOINT로 컨테이너 시작 시 실행할 명령어를 지정한다.

# 베이스 이미지 선택  
FROM openjdk:17-jdk-slim  
  
# 작업 디렉토리 설정  
WORKDIR /app  
  
# JAR 파일 복사  
COPY target/*.jar app.jar  
  
# 실행 명령  
ENTRYPOINT ["java", "-jar", "app.jar"]

2. Docker 빌드

프로젝트 빌드

• IDE 터미널에서 clean package로 테스트를 포함한 전체 빌드를 수행한다.
  • -DskipTests 옵션을 추가하면 테스트를 생략할 수 있다.
• Maven

./mvnw clean package

Docker 빌드

• 프로젝트 빌드 후엔 터미널에서 Docker 이미지를 빌드한다.
  • -t는 태그 옵션으로, 이미지의 이름과 태그를 지정한다.

docker build -t <이미지명:태그> <Dockerfile경로>

docker build -t myapp:latest .

• docker images로 생성한 이미지 파일을 확인할 수 있다.

docker images

3. Docker 실행

Docker 컨테이너 실행

• docker run을 사용해서 컨테이너를 실행한다.
  • -d : Detached 모드로, 백그라운드에서 컨테이너가 실행되어 터미널에 로그가 출력되지 않는다.
  • -p 호스트:컨테이너 : 포트 포워딩 설정으로 호스트 포트로 들어오는 요청을 컨테이너 내부 포트로 전달한다.
  • --name <이름> : 실행할 컨테이너에 이름을 부여한다.

docker run -d -p <호스트:컨테이너> --name <이름> <이미지명:태그>

docker run -d -p 8080:8080 --name myapp myapp:latest

• docker ps로 실행 중인 docker 컨테이너 정보를 확인할 수 있다.

docker ps

• docker를 실행한 후 웹 브라우저에서 Controller에 설정한 /api mapping으로 접근해서 docker 컨테이너에 복사된 빌드 파일(애플리케이션)이 작동 중인지 확인한다.

• Docker Desktop에서도 실행 중인 컨테이너를 확인할 수 있다.

Docker 대화형 Shell 모드로 실행

• docker exec 명령어를 터미널에 입력하면 대화형 Shell 모드로 컨테이너를 실행할 수 있다.
  • -it : interactive, pseudo-tty 할당으로 Shell을 통한 터미널 접근 및 입력 가능

docker exec -it <이미지이름:태그> <실행명령어>

docker exec -it myapp /bin/sh

컨테이너 타임존 설정

• docker exec -it <이름> /bin/sh 명령어로 Shell 모드 접근 후 date로 현재 컨테이너의 시간을 확인할 수 있다.

date

• 타임존 변경을 위해 tzdata 패키지를 설치한다.
  • alpine 이미지라면 apk add를 사용한다.
  • ubuntu, debian 등의 이미지라면 apt install을 사용한다.

# alpine 이미지
apk add tzdata

# python:slim, debian, ubuntu 등
apt install tzdata

• 패키지 설치 시 현재 컨테이너의 OS를 확인하게 OS에 맞는 명령어를 사용하면 된다.

cat /etc/os-release

• 이제 타임존을 다음 명령어로 UTC에서 KST로 변경한다.

# 타임존 변경
echo "Asia/Seoul" > /etc/timezone
export TZ=Asia/Seoul

# 날짜 다시 확인
date

• shell을 빠져나올 때는 exit으로 나올 수 있다.

# shell 종료
exit

Docker 종료

• docker를 종료할 때는 docker stop으로 종료한다.

docker stop <이름>

docker stop myapp

사용하지 않는 Docker 리소스 정리

• 사용하지 않는 Docker 컨테이너, 이미지, 네트워크, 캐시 등을 정리할 때 docker system prune을 사용한다.
  • -a : 모든 이미지 제거

docker system prune -a

docker-compose.yml 사용 시

• 참고 자료 : James Walker's Docker Compose - What is it, Example & Tutorial
• docker-compose.yml에는 Spring boot 애플리케이션의 의존성이나 포트, 컨테이너 설정 등의 여러 설정을 관리할 수 있다.

# Docker Compose 파일 포맷 버전
version: '3.8'

services:
	# app 서비스
	app:
	    build:
			context: .
	    image: my-spring-app:latest
	    container_name: my-spring-app
	    ports:
			- "8080:8080"
	    # 의존성 설정
	    depends_on:
			- db
	    environment:
			SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/mydatabase
			SPRING_DATASOURCE_USERNAME: myuser
			SPRING_DATASOURCE_PASSWORD: mypassword

	# db 서비스
	db:
		# postgresql 서비스 정의
		image: postgres:14-alpine
		container_name: my-app-db
		ports:
			- "5432:5432"
		environment:
			POSTGRES_DB: mydatabase
			POSTGRES_USER: myuser
			POSTGRES_PASSWORD: mypassword
		volumes:
			- db_data:/var/lib/postgresql/data

# db 데이터 지속적으로 유지
volumes:
	db_data:

• docker-compose up 명령어를 사용하면 docker-compose.yml에 설정된 내용으로 docker 컨테이너를 빌드 및 실행할 수 있다.
  • -d : detached 모드로 백그라운드에서 실행한다.

docker-compose up -d

• docker-compose logs로는 컨테이너 로그를 출력할 수 있다.
  • -f : follow 모드로 로그가 지속해서 출력된다.

docker-compose logs -f

• docker-compose down은 docker-compose.yml로 정의된 컨테이너 중 실행 중인 서비스들을 중지 및 제거한다.

docker-compose down